docs(hyperframes): noventa lecciones medidas, siete herramientas de verificación y el estilo measured-light - #9

Qué es

Usé el kit para producir piezas y medir cada afirmación contra referencias reales de motion graphics. El proceso dejó un conjunto de hallazgos que contradicen o completan lo que el skill de hyperframes ya decía, más las herramientas que sostienen esas afirmaciones y un estilo nuevo para la biblioteca.

Todo lo que se afirma en el documento está medido, no estimado.

Qué cambia

references/lecciones-medidas.md — noventa lecciones

Enlazado como primera referencia del SKILL.md, con la nota de que donde contradiga al resto del skill gana, porque está medido. Van en ocho grupos con índice, ordenados por el momento en que hacen falta: El motor · Fluidez · Composición y texto · Color, luz y fondo · Objetos y técnicas · Movimiento · Entrega y formatos · Método e instrumentos.

Lo que ya estaba:

• Trampas del motor de captura por seek. immediateRender muerde en las dos direcciones: con el default el elemento se congela en su estado inicial desde el cuadro 0, y con false muestra su estado final desde el cuadro 0. También: los fundidos que terminan en un límite de clip necesitan un tl.set duro, no hay obturador —todo el motion blur es autoreado—, y los valores relativos (+=, -=) rompen bajo render en paralelo.
• La escala real de un travelling. Medido cuadro a cuadro: el objeto pasa del 13 % al 88 % del ancho en 3,8 s. Un empuje de 1,0 a 1,15 no es una cámara.
• Medición de texto. Ninguna es válida antes de document.fonts.ready: offsetWidth devuelve el ancho de la tipografía de respaldo, 23 % menor.
• Ritmo, tiempo de lectura (17 CPS), audio y método de verificación, incluido el A/B pareado por timestamp contra la referencia.

Lo nuevo de esta tanda — material vectorial, medido produciendo una pieza contra la técnica de prompt → SVG editable → cada trazo animado:

• Cuando el gráfico es un diagrama, un esquema o un plano, el material correcto es SVG en línea. 179 trazos son 179 nodos que GSAP alcanza. Un <img src="algo.svg"> no sirve.
• pathLength="1" normaliza el guion. Medido: el trazo recto más corto y el más largo se llevan 59 a 1; sin normalizar, el mismo tween deja el dibujo emparchado.
• 🚨 vector-effect: non-scaling-stroke y pathLength no conviven. El plano aparece punteado desde el cuadro cero —el stroke-dasharray: 1 vuelve a medirse en píxeles— y de paso infló la medición de fluidez de 1,45 a 2,02: el instrumento contaba el titileo como movimiento. Y vector-effect no se hereda: va en el path, no en el <svg>.
• 🚨 En SVG, GSAP no usa transform-origin: hornea el pivote en una matriz calculada desde el bounding box. Va por svgOrigin, en coordenadas del viewBox. Sin eso un diafragma no cierra: las palas se van del cuadro.
• 🚨 transform-box: view-box mide desde la esquina min-x min-y del viewBox, no desde (0,0). Si el viewBox arranca corrido, todo lo que gira se va a otro lado.
• El barrido de un zoom es radial. v(r) = r · dS/dt: cero en el punto fijo, 12,4 px de σ en el borde. Un desenfoque parejo está mal en los dos lugares. Se resuelve con una capa de backdrop-filter enmascarada por un gradiente radial, hermana de lo que escala y nunca hija —si no, la máscara escala con el zoom.
• El trazo vectorial se multiplica por la escala. A 7,5× un stroke-width de 2,6 se dibuja de 19,5 px. sw = ancho_en_pantalla / (k · escala), animado con el mismo ease que la cámara.
• La cola de un power2.inOut mata el cuadro: 0,6 s marcados como quietos al final de un zoom de 2,85 s.
• 🚨 Un tipeo no sostiene un plano. Un carácter de 40 px pinta ~300 píxeles sobre 2.073.600. Y la cámara sobre un cuadro vacío tampoco mueve nada. De 39 % a 13 % de cuadros quietos poniendo algo que cruce el cuadro.
• El cursor de un tipeo se lee del layout, no se estima: un <span> por carácter y offsetLeft + offsetWidth.

scripts/lab/ — siete herramientas, con su manual

README.md documenta el orden en que se usan y lo que no es obvio de cada una. Arranca por ahí porque dos veces un chequeo automático inventó problemas que no existían: antes de creerle a una medición rara, verificar el instrumento.

Todo con ffmpeg, Node y Pillow.

style-library/03-measured-light/ — el registro claro

Papel #F3F4F9, tinta #0A0A14, acento #1D1DE8. El texto va negro sobre claro y el color vive únicamente en los objetos.

Los tokens no son de gusto: son umbrales medidos y están para calcular con ellos — --sostener-px-s: 60 (recorrido/duración mínimo de una cámara sobre superficie plana), --obturador: 0.9 (σ = (px_s / fps) · obturador / 3) y --lectura-cps: 17. Cuatro cartas, DESIGN.md con lo que no se hace, y el registro reconstruido: 3 estilos, 410 cartas, 0 avisos.

Correcciones a contenido existente

• references/typography.md prohibía tipografías sin advertir que el motor sólo embebe 18 familias. Siguiendo la lista tal como estaba se podía elegir una que no está embebida y el render caía a la de respaldo en silencio.
• references/motion-principles.md proponía animar letterSpacing como variación de entrada, y el propio lint del motor lo rechaza: reflowea el texto y se clava a píxeles enteros, así que tiembla bajo la captura por seek.
• scripts/check-kit.mjs recorre el disco, no el índice de git. Un entorno virtual de Python local —el que pide Kokoro para el TTS— le metía 1.404 errores de archivos que nunca van al repo. Se suman .venv, .venv-tts, venv y __pycache__ a la lista de carpetas que ya salta.

Para el revisor

• El documento está en español. Si preferís que el kit mantenga todo en inglés, lo traduzco sin problema — decímelo y lo hago en este mismo PR.
• .claude/ y .agents/ están sincronizados con npm run sync:skills, como pide el CLAUDE.md del repo.
• Verificado: npm run check da 711 archivos, 3 estilos, 410 cartas, 0 errores; npm run sync:skills reporta 95 archivos y 0 discrepancias.
• Las herramientas van en scripts/lab/ y no en video-projects/, que está en .gitignore — las referencias del documento apuntan ahí.
• Las piezas de laboratorio no se incluyen: video-projects/ está ignorado, tal como pide el CLAUDE.md del repo. El documento describe las mediciones sin depender de esos archivos.
• El corpus de referencias de motion graphics tampoco se incluye: es material de terceros.

🤖 Generated with Claude Code